docs(mosaico_integration): clarify bridge SSE flow and link entity-discovery upstream issue

- Rewrite the module docstring architecture block as a sequential 4-step
  flow (SSE in, REST out, MCAP back, Arrow Flight to mosaicod). The old
  inline arrows mixed request directions on one line and were hard to
  follow.
- Add a roadmap pointer in resolve_entity_for_download(): the HEAD-probe
  discovery is a pragmatic workaround for the fact that the gateway-wide
  /faults/stream SSE does not include SOVD entity context. Tracked in
  selfpatch/ros2_medkit#380; once that lands the function collapses to a
  single direct fetch.

Author: Michał Fąferek

demos/mosaico_integration/bridge/bridge.py

@@ -3,8 +3,10 @@
 snapshot bag into mosaicod via the mosaicolabs Python SDK.
 
 Architecture:
-  medkit gateway --(SSE)--> bridge --(REST)--> medkit gateway --(MCAP)--> bridge
-  bridge --(Arrow Flight via mosaicolabs)--> mosaicod
+  1. medkit gateway  --[SSE: fault event]-->   bridge
+  2. bridge          --[REST: GET snapshot]-->  medkit gateway
+  3. medkit gateway  --[MCAP bag response]-->   bridge
+  4. bridge          --[Arrow Flight]-->        mosaicod
 
 License-safe: this is a separate process talking Arrow Flight to an
 unmodified mosaicod docker image, per Mosaico's recommended pattern.
@@ -191,6 +193,11 @@ def resolve_entity_for_download(
     - We discover the right entity by listing all apps + components and
       asking each for the bulk-data/rosbags/{fault_code} until one returns 200.
       The list is small (~10 entities) so this is cheap.
+    - This HEAD-probe discovery is a pragmatic workaround. The gateway-wide
+      SSE fault stream does not surface SOVD entity context today; tracked
+      in selfpatch/ros2_medkit#380 (either an x-medkit extension in the SSE
+      payload or per-entity fault subscriptions). Once that lands, this
+      function collapses to a single direct fetch.
     """
     # Build candidate list: enumerate apps and components.
     candidates: list[tuple[str, str]] = []