docs(zod-schema): add warning about .meta() / .describe() method chaining order (#10452)

## Summary

Adds a warning note explaining that `.meta()` and .`describe()` must be
called at the end of schema method chains to preserve metadata in JSON
schema output, (just to prevent confusion)

## Related Issues

closes #10005
see also colinhacks/zod#5447

Author: IdoBouskila

content/docs/07-reference/01-ai-sdk-core/26-zod-schema.mdx

@@ -17,6 +17,26 @@ You can use it to [generate structured data](/docs/ai-sdk-core/generating-struct
   the `zodSchema()` helper function instead.
 </Note>
 
+<Note type="warning">
+  When using `.meta()` or `.describe()` to add metadata to your Zod schemas,
+  make sure these methods are called **at the end** of the schema chain.
+  
+  metadata is attached to a specific schema
+  instance, and most schema methods (`.min()`, `.optional()`, `.extend()`, etc.)
+  return a new schema instance that does not inherit metadata from the previous one.
+  Due to Zod's immutability, metadata is only included in the JSON schema output
+  if `.meta()` or `.describe()` is the last method in the chain.
+
+```ts
+// ❌ Metadata will be lost - .min() returns a new instance without metadata
+z.string().meta({ describe: 'first name' }).min(1);
+
+// ✅ Metadata is preserved - .meta() is the final method
+z.string().min(1).meta({ describe: 'first name' });
+```
+
+</Note>
+
 ## Example with recursive schemas
 
 ```ts