Fix #246: Add Model Hub architecture documentation for developers

README.md

@@ -378,3 +378,31 @@ Browse and discover AI models on the [OpenGradient Model Hub](https://hub.opengr
 
 - Visit our [documentation](https://docs.opengradient.ai/) for detailed guides
 - Join our [community](https://discord.gg/axammqTRDz) for support and discussions
+
+## Model Hub Architecture
+
+Model Hub is the model registry and discovery layer. It manages model metadata, versioning, and serves inference endpoints.
+
+### Where Model Hub fits in an application
+
+```
+User Input → Agent/App → Model Hub (discovery) → SDK Inference → Post-processing → Output
+                              ↕
+                      On-chain TEE Registry
+```
+
+### When to call Model Hub directly vs through the SDK
+
+- **Model Hub directly**: Use when you need to list available models, query model metadata (CID, provider, description), or discover which models are registered.
+- **SDK inference** (`og.LLM.chat()` / `og.LLM.completion()`): Use for running inference. The SDK internally resolves the TEE endpoint from the registry and handles x402 payments, retries, and TEE rotation.
+
+### State and memory
+
+Model Hub is stateless — it only stores model metadata on-chain. For conversation state or agent memory, use your own storage layer (e.g., database, in-memory cache) alongside Model Hub.
+
+### Typical flow
+
+1. Call `client.list_models()` to discover available models
+2. Select a model by its ID
+3. Pass the selected model to `llm.chat()` or `llm.completion()`
+4. The SDK handles TEE routing, payment, and attestation verification