docs: explain Telnyx warm-transfer caller ID preservation

[piyush-gambhir]

A warm transfer creates a new outbound call to the human agent. Applications using Telnyx may want that recipient to see the original customer's number, so caller-ID-based identification and lookup can continue through the handoff.

The SDK already exposes the caller number and SIP headers needed for this. This PR documents how to use those options together, without introducing a provider flag or new runtime behavior.

What this adds

• An inbound A → Telnyx B → supervisor C example using the customer's number and a Diversion header identifying B.
• Instructions to obtain normalized numbers from trusted per-call context and select the Telnyx outbound trunk.
• The requirement to keep the original inbound call active, plus troubleshooting for 403 Unverified origination number D51.
• A manual live-call verification checklist, including caller-ID display and successful consultation/transfer.

The carrier requirements are grounded in Telnyx's external call transfer documentation. Telnyx checks both the active inbound call and the diversion information; a header alone does not authorize an arbitrary caller ID.

This contribution is independent of the Twilio CallToken PRs and is based directly on main.

Validation

• Parsed both Python task snippets and checked constructor keyword names against WarmTransferTask.
• Corrected the existing README snippet's outdated target_phone_number argument to sip_call_to.
• make fix and repository formatting/lint checks passed; git diff --check passed.
• Full make check stops in the local core-only environment because optional plugin type information is missing (first: livekit.plugins.anam).
• No runtime behavior changed; no live Telnyx call was placed. Carrier acceptance and caller-ID presentation remain live-test steps.

Live QA status

Telnyx live carrier validation has not been completed. The available QA environment has a configured LiveKit Telnyx outbound trunk but lacks the Telnyx API credentials needed to provision/control a dedicated inbound test number. The separate Twilio CallToken live tests do not validate this SIP Diversion flow. Carrier acceptance and caller-ID presentation remain outstanding.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.