apacheGH-37720: [Format][Docs][FlightSQL] Document FlightSQL stateles…

…s prepared statements

docs/source/format/FlightSql.rst

@@ -141,6 +141,9 @@ the ``type`` should be ``ClosePreparedStatement``).
     Execute a previously created prepared statement and get the results.
 
     When used with DoPut: binds parameter values to the prepared statement.
+    The server may optionally respond with an updated handle. The client
+    should use this updated handle for all subsequent requests for this
+    prepared statement.
 
     When used with GetFlightInfo: execute the prepared statement. The
     prepared statement can be reused after fetching results.

docs/source/format/FlightSql/CommandPreparedStatementQuery.mmd

@@ -28,6 +28,8 @@ Server->>Client: ActionCreatePreparedStatementResult{handle}
 loop for each invocation of the prepared statement
 Client->>Server: DoPut(CommandPreparedStatementQuery)
 Client->>Server: stream of FlightData
+Server-->>Client: DoPutPreparedStatementResult{handle}
+Note over Client,Server: optional response with updated handle
 Client->>Server: GetFlightInfo(CommandPreparedStatementQuery)
 Server->>Client: FlightInfo{endpoints: [FlightEndpoint{…}, …]}
     loop for each endpoint in FlightInfo.endpoints