docs(auth): fix /verify endpoint documentation to match validation logic

[rajpohekar]

What changed

• Updated POST /verify documentation to reflect actual validation rules
• Documented the two supported verification flows:
  • token + email / phone
  • token_hash
• Added missing request fields (email, phone, token_hash)
• Corrected the list of supported type values
• Added realistic request examples for email, SMS, and magic link verification
• Clarified GET /verify behavior where token is treated as a token_hash

Why

The existing README described request payloads that do not match the current
validation logic in internal/api/verify.go, which results in confusing
validation_failed errors for users following the docs.

This PR aligns the documentation with the implementation without changing any
runtime behavior.

Scope

• Documentation only
• No API or behavior changes

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Enhanced API documentation for verification methods, clarifying distinct behaviors and requirements for POST and GET endpoints
  • Added explicit field requirements and validation rules with comprehensive examples
  • Included detailed verification flow sections for better endpoint understanding
  • Updated backward compatibility notes with improved wording

Walkthrough

The README.md documentation has been updated to clarify the POST /verify and GET /verify verification methods. The changes replace a previous multi-type description with two mutually exclusive verification approaches: one using token with email/phone fields, and another using token_hash. Updates include explicit field requirements, validation rules, a new magiclink token_hash example, inclusion of email in the POST /verify token payload, and adjustments to the GET /verify description noting that the token query parameter is treated as token_hash internally. Minor wording changes were also made to the backward compatibility note.

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}