Improve: update and enhance slot migration API documentation

[alok-kumar0421]

Summary

This PR improves the Slot Migration API documentation in docs/API.md.
The earlier version of this section was incomplete and did not fully explain the fields, behavior, or possible responses of the migration endpoint.
Since this API is important for resharding and operational workflows, having accurate documentation is essential.

---

Improvements in This PR

• Added missing fields used by the migration endpoint
  (slot_only, pipeline_size, speed)
• Corrected slot_only to boolean, matching the real API behavior
• Added clear descriptions for each request parameter
• Documented all relevant response types, including error cases
• Explained the migration lifecycle and slot state transitions
• Improved formatting to keep it consistent with the rest of the API docs

---

Motivation

Users relying on slot migration (especially for automation or cluster maintenance) need complete and reliable documentation.
The previous version did not cover several important details, which could cause confusion or incorrect usage.
This update aims to provide a clearer and more accurate reference for anyone interacting with the migration API.

---

Notes

• This PR changes documentation only
• No functional code is modified
• Open to feedback if maintainers want additional clarification or examples