docs: update ReadOnlyContext.state to use MappingProxyType with an improved docstring

Author: timof1308

src/google/adk/agents/readonly_context.py

@@ -53,8 +53,14 @@ def agent_name(self) -> str:
     return self._invocation_context.agent.name
 
   @property
-  def state(self) -> Mapping[str, Any]:
-    """The state of the current session. READONLY field."""
+  def state(self) -> MappingProxyType[str, Any]:
+    """The state of the current session. READONLY field.
+
+    Note: This property returns a merged view of ephemeral request_state and
+    persistent session.state using ChainMap. Changes to the underlying
+    request_state or session.state dictionaries will be reflected through
+    this view, but direct writes through this property are prevented.
+    """
     return MappingProxyType(
         ChainMap(
             self._invocation_context.request_state,