Document `reason` parameter behavior for SWML `hangup` method

[akalsey]

Document reason parameter behavior for SWML hangup method

Description

The documentation for the SWML hangup method lists three possible values for the reason parameter (hangup, busy, decline) but provides no explanation of what each reason does, what SIP response codes they map to, or which call states each reason is valid in.

Without this information, developers have no way to know what effect each reason has or when to use each one. The distinction between these reasons matters because they likely map to different SIP response codes (e.g., busy → 486 Busy Here, decline → 603 Decline, hangup → BYE) and are only semantically meaningful in specific call states.

The existing example compounds the problem by showing busy used after an answer, which is a nonsensical combination — a call that has already been answered cannot meaningfully be ended with a "busy" signal. This example actively misleads developers about how the parameter works.

The documentation should:

• Describe the behavior of each reason value (e.g., what SIP response code is sent, what the caller experiences)
• Specify which call states each reason is valid in (e.g., busy and decline are only valid for unanswered/ringing calls; hangup is for answered calls)
• Document what happens if an invalid reason is used for the current call state (is it ignored? does it error? does it fall back to default behavior?)
• Document the default behavior when no reason is provided, for each call state. For example, if hangup is called with no reason on an unanswered inbound call, what does the caller experience? Do they hear a busy signal, a generic rejection, dead air, or a carrier-level error message?
• Fix the example to show a realistic use case, such as using busy or decline on an inbound call before answering it

Ideally, the docs would include a matrix of reason × call state showing the resulting behavior and SIP response codes.