docs(UPIIS-47): document alias, param defaults, otpRequired semantics

[Anindya-Pandey]

What

Aligns the UPI Issuance docs and OpenAPI reference with the service's actual
behaviour. Each item below is something a client would have hit in practice
that the docs either omitted or described wrongly.

alias is now documented

alias ships in binding-status and otp/verify responses today, but appeared
nowhere in the docs or the API reference — so the reference disagreed with what
clients actually receive.

Added to the shared user object table and the UserView schema, plus the
four inline response examples.

The set-alias endpoint is deliberately left undocumented for now. Only
the response field is described, so the docs match observed behaviour without
exposing the call.

Defaults for optional params

Optional params that silently defaulted now say so:

Param	Behaviour when omitted
otpRequired (create-vpa)	defaults to false
defaultDebit / defaultCredit	default to false
programId	VPA is created without a program
update-program (all fields)	omitted fields keep their current value

otpRequired reframed

The docs read as though Setu enforced the OS pairing ("This is OS-dependent").
It isn't — otpRequired is passed straight through and is never validated
against os. The flow follows whatever is sent.

Reframed as the value Setu expects the TPAP / Issuing App to send, hedged as
per current understanding, with a new "Choosing the otpRequired value"
section carrying the expectation table.

VPA prefix accuracy fix

Corrected in 8 places across the 4 VPA endpoints:

• before — "Its VPA prefix must start with the subscriber's mobile."
• after — "Its VPA prefix must start with the user's alias — by default, the
  user's mobile number."

The old wording is simply wrong for any user with a custom alias. This matches
the service spec: "Its prefix must start with the user's alias (which defaults
to their mobile)."

Voice and samples

• Second person → TPAP / Issuing App across all pages (21 rewrites), matching
  the convention already used elsewhere in these docs. Also removed a stray
  first-person "so we can authenticate".
• VPA sample suffix alice → acme, since the suffix is a program code and
  "Acme Wallet" / ACME is already the program example in these docs. A person's
  name there was misleading.
• accountName: "Alice Doe" left as-is — a person's name is correct for the
  account holder.

Verified

• Every claim checked against the service repo (spec/tpapapi/,
  internal/pkg/onboarding/) rather than inferred from the existing docs.
• All 12 UPI Issuance pages render 200 locally against this branch's content.
• OpenAPI spec re-validates as JSON; formatting preserved (1-space indent, no
  trailing newline) so the diff is content-only.
• No set-alias / setAlias reference anywhere in docs or spec.

Note for reviewers

The spec diff looks large (86 lines) but ~38 of those are the mechanical
alice@setu → acme@setu example swap. The structural change is just the
alias property plus its examples.

[github-actions]

Checklist to merge a PR 🚀

To merge this pull request, please take time to complete the checklist.

What action did you perform?

Review the corresponding checklist items for the action you performed and mark them done.

Edit an existing content (MDX) page

Checklist

• Review changes using the MDX preview option
• If the length of content >15000 chars, use the Content preview portal to view changes
• If a redirect is needed to the existing page, add a key, value pair in redirects.json

---

Edit an existing API reference page

Checklist

• Use the Content preview portal to view changes
• API reference is in JSON format (OpenAPI or Swagger)

---

Add a new content (MDX) page

Checklist

• Create a .mdx file with the path as its name in the content folder
• Add frontmatter with all the metadata
• Review the order of items in Sidebar using the Sidebar preview option
• Review changes using the MDX preview option
• If the length of content >15000 chars, use the Content preview portal to view changes
• Created a folder with the same name, if any children were to be added to the page
• Once all changes are done, update the menu items by using the Menu Items option
• Add a key, and value pair in redirects.json if you wish to have a redirect to the new page

---

Add a new API reference page

Checklist

• Create a .json file with the product path as its name
• Create an api-reference.mdx file in the respective product folder inside content folder
• Add frontmatter with all the metadata
• Review the order of items in Sidebar using the Sidebar preview option
• Add API reference in JSON format (OpenAPI or Swagger) into created .json file.
• Used the Content preview portal to view changes
• Once all changes are done, update the menu items by using the Menu Items option