Fix zone transfer request update API documentation

The API reference incorrectly suggested target_project_id could be
freely updated. In reality, it has write-once behavior: settable from
null to a value, but immutable once set.

Changes:
* Added note explaining target_project_id and zone_id immutability
* Documented delete + recreate pattern for changing target project
* Updated request sample to show only description update
* Updated response sample to include all actual API fields and match
  CREATE response for consistency

Assisted-By: Claude Code 4.5 Sonnet
Closes-Bug: #1978710
Change-Id: Ie8be7a86ffe8a685ba2692456643ed1779bad7af
Signed-off-by: Omer <oschwart@redhat.com>

api-ref/source/dns-api-v2-zone-ownership-transfer-request.inc

@@ -204,6 +204,18 @@ Update a Zone Transfer Request
 
 .. rest_method::  PATCH /v2/zones/tasks/transfer_requests/{zone_transfer_request_id}
 
+This allows you to update a zone transfer request.
+
+.. note::
+
+   The ``zone_id`` field is immutable and cannot be updated.
+
+   The ``target_project_id`` field can be set once via PATCH if it was not
+   specified during creation (i.e., if it is currently ``null``). However, once
+   set, it cannot be modified or cleared. To change the target project after it
+   has been set, you must delete this transfer request and create a new one.
+   This ensures a new transfer key is generated.
+
 
 .. rest_status_code:: success status.yaml
 

api-ref/source/samples/zones/create-zone-transfer-request-request.json

@@ -1,3 +1,3 @@
 {
-    "project_id": "1"
+    "target_project_id": "123456"
 }

api-ref/source/samples/zones/update-zone-transfer-request-request.json

@@ -1,4 +1,3 @@
 {
-    "description": "This is scoped to the new project",
-    "target_project_id": "987654"
+    "description": "Transfer request for qa.dev.example.com."
 }

api-ref/source/samples/zones/update-zone-transfer-request-response.json

@@ -1,11 +1,15 @@
 {
-    "description": "This is scoped to the new project",
-    "target_project_id": "987654",
-    "id": "efd2d720-b0c4-43d4-99f7-d9b53e08860d",
-    "zone_id": "2c4d5e37-f823-4bee-9859-031cb44f80e7",
-    "zone_name": "subdomain.example.com.",
+    "created_at": "2014-07-17T20:34:40.882579",
+    "description": "Transfer request for qa.dev.example.com.",
+    "id": "f2ad17b5-807a-423f-a991-e06236c247be",
+    "key": "9Z2R50Y0",
+    "project_id": "1",
     "status": "ACTIVE",
+    "target_project_id": "123456",
+    "updated_at": "2014-07-17T20:35:00.000000",
+    "zone_id": "6b78734a-aef1-45cd-9708-8eb3c2d26ff8",
+    "zone_name": "qa.dev.example.com.",
     "links": {
-        "self": "http://127.0.0.1:9001/v2/zones/tasks/transfer_requests/efd2d720-b0c4-43d4-99f7-d9b53e08860d"
+        "self": "http://127.0.0.1:9001/v2/zones/tasks/transfer_requests/f2ad17b5-807a-423f-a991-e06236c247be"
     }
 }